/*
 *	AudioOutputStream.java
 *
 *	This file is part of Tritonus: http://www.tritonus.org/
 */

/*
 *  Copyright (c) 2000 by Matthias Pfisterer
 *
 *
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU Library General Public License as published
 *   by the Free Software Foundation; either version 2 of the License, or
 *   (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU Library General Public License for more details.
 *
 *   You should have received a copy of the GNU Library General Public
 *   License along with this program; if not, write to the Free Software
 *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 */

/*
 |<---            this code is formatted to fit into 80 columns             --->|
 */

package org.tritonus.share.sampled.file;

import java.io.IOException;

import javax.sound.sampled.AudioFormat;

/**
 * Represents a one-time writing of audio data to a destination (file or output
 * stream).
 * 
 * This interface is the lowest abstraction level of writing audio data.
 * Implementations of this interface should, when write() is called, never do
 * buffering and they should never do format conversions. However, this
 * interface is intended to abstract the file format (how the headers and data
 * chunks look like) and the way of writing to the destination object.
 * (implementation note [non-normative]: the last should be done by using
 * TDataOutputStream implementing classes).
 * 
 * One reasoning behind this interface was to allow direct, unbuffered writing
 * of recorded data. In JS API 0.90, there was no obvious way for this. Data
 * have had to be recorded to a buffer, then written to a file from that buffer.
 * This gave problems with long recordings, where the main memory of the machine
 * is not big enough to hold all data. There are two ways so solve this:
 * 
 * a) Having a special AudioInputStream that fetches its data from a
 * TargetDataLine. This way, the loop inside the AudioFileWriters reads
 * directely from the recording line via the special AudioInputStream. This is
 * the solution Sun adopted for JS 1.0.
 * 
 * b) The other way is to expose a direct interface to the writing of the audio
 * file with no loop inside it. This is to enable the application programmer to
 * write the main loop itself, possibly doing some additional processing inside
 * it. This is the more flexible way. The drawback is that it requires a new
 * architecture for writing files.
 * 
 * This interface is the central part of a proposal for the second solution. The
 * idea is now to use the new structure inside the old one to gain experience
 * with it before proposing to make it a public interface (public in the sense
 * that it is part of the javax.sound.sampled package).
 * 
 * @author Matthias Pfisterer
 */
public interface AudioOutputStream extends AutoCloseable{
	/**
	 * Retrieves the AufioFormat of this AudioOutputStream.
	 */
	public AudioFormat getFormat();

	/**
	 * Gives length of the stream. This value is in bytes. It may be
	 * AudioSystem.NOT_SPECIFIED to express that the length is unknown.
	 */
	public long getLength();

	/**
	 * Writes a chunk of audio data to the destination (file or output stream).
	 */
	// IDEA: use long?
	public int write(byte[] abData, int nOffset, int nLength) throws IOException;

	/**
	 * Closes the stream. This does write remaining buffered data to the
	 * destination, backpatch the header, if necessary, and closes the
	 * destination.
	 */
	public void close() throws IOException;
}

/*** AudioOutputStream.java ***/
